/**
   CS 305 & 503, Data Structures and Algorithms
   Programming Assignment 1, Fall 2010

   An interface for simple, linear, link-based ADTs: linked lists, stacks,
   queues, and the like.  The ADTs are generic in the type of the value stored.

   Values in a linked sequence are accessed via indices, similar to the way
   array values are accessed.  However, unlike arrays, the indices into a
   linked sequence reference between adjacent values rather than the values
   themselves:

        +----+   +----+          +----+   
    |---| e1 |---| e2 |--- ...---| en |---|
        +----+   +----+          +----+	
      |        |        |      |        |
      0        1        2     n-1       n

   Not all indices are valid for all linked sequences (n is the number of
   values in the linked-sequence ADT):

     ADT          Valid indices

     stack        i = 0

     queue        i = 0 or i = n

     linked list  0 <= i <= n

   The operation being performed on a linked sequence also determines if an
   index is valid.  For example, when adding a value to a linked list, n is a
   valid index; but n would be invalid when seeing a value in a linked list.
 */


public interface
LinkedSequence<E> {

  /**
     Determine the number of values in this linked sequence.

     @return The index of the last link in this linked sequence.
   */

  public int end();


  /**
     Remove a value from this linked sequence.

     @param The index of the value to remove.

     @throws An IndexOutOfBoundsException if i is not valid; i is valid when

       stack:        i = 0
       queue:        i = 0
       linked list:  0 <= i < end()
   */

  public void get(int i);
  

  /**
     Insert a value into this linked sequence.

     @param i The index at which the value will be inserted.

     @param v The value to insert.

     @throws An IndexOutOfBoundsException if i is not valid; i is valid when

       stack:        i = 0
       queue:        i = end()
       linked list:  0 <= i <= end()
   */

  public void put(int i, E v);


  /**
     Return a value in a linked sequence.

     @param i An index.

     @return The value at index i.

     @throws An IndexOutOfBoundsException if i is not valid; i is valid when

       stack:        i = 0
       queue:        i = 0
       linked list:  0 <= i < end()
   */

  public E see(int i);

  }


// $Log: LinkedSequence.java,v $
// Revision 1.4  2010/10/05 04:58:30  rclayton
// Correct the valid index values for queue.put().
//
// Revision 1.3  2010/09/29 13:02:44  rclayton
// Describe valid index ranges.
//
// Revision 1.2  2010/02/20 21:27:45  rclayton
// Clarify see()'s behavior.
//
// Revision 1.1  2010/02/02 19:04:46  rclayton
// Initial revision
